Change Tours

Characteristic

Detailed Consideration

The basis for a ChangeToursRequest is an existing tour plan. To be able to modify that plan, the PTV xTour service needs access to the current state of tours. For this purpose, a session storage is used.

After storing the initial PlanToursRequest, the tour plan can be modified via a ChangeToursRequest and the changed state of the plan is automatically stored again for further manipulations.

Usage of ChangeToursRequest

At first it is necessary to create a tour plan with a PlanToursRequest. Remember to set the field storeRequest to true to be able to use the session storage. Then create a ChangeToursRequest using the storedRequestId from the ToursResponse as storedRequestId in the desired ChangeToursAction. For further details also see How to Change Stored Tours.

ChangeToursActions with specified insertion positions

For the ChangeToursActions that move orders, stops or trips to another position it is important to specify a valid insertion position. There are two important points to keep in mind when choosing an insertion position that will be explained below in the example of a MoveStopsAction.

• Partner tasks:

  The partner task of a pickup task is the delivery task of the same transport order and vice versa. If a stop to be moved contains a delivery or pickup task, the insertion position of the partner task needs to be uniquely identifiable. For example, if the stop to be moved contains a pickup task, the location of the corresponding delivery task needs to be contained in the target trip after the specified insertion position of the original stop. The only exception from that rule is if the delivery task takes place at a depot and the target trip does not yet end at a depot, the delivery task will be automatically inserted at the end of the trip.

• Tour structure:

  A ChangeToursRequest is not allowed to change trips that are not part of the explicitly defined change. That means there should be no new trips created and no two old trips should be merged to one. If that is the case, a TourStructureFault is thrown. According to the definition of a trip (see Tours and Trips) especially the movement of a depot stop can lead to a new trip in the target tour or to a trip merge in the source tour.

  Furthermore, it is an undesired tour structure to visit a location again while there is still load on the vehicle that was picked up from the same location. Analogously, it is not desired to leave a location while there is still load for it on the vehicle. Hence, a ChangeToursRequest violating those rules is infeasible.

  Also the stop structure "delivery tasks before visit tasks before pickup tasks" needs to be respected (see Orders, Locations, and Stops).

ChangeToursActions containing automated planning functionality

There are some ChangeToursActions that use automated planning functionality. Those are even more comfortable to use because you do not have to think about the validity of tours yourself as explained in the cases above.

Some examples of these actions are:

• InsertionAtBestPosition:

  The option of an insertion at best position is for example usable in a MoveOrdersAction. The corresponding order is automatically inserted at the best position in the target trip, that means the best position concerning the overall tour travel and driving time.

• AddTripAction:

  This action adds a complete trip to a vehicle The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition., in the most simple case to an unused one. The sequence of all orders contained in the AddTripAction is automatically determined to form a valid trip. If all of the orders in combination lead to a violated trip (for further information have a look at the section below), some of them stay unplanned.

• OptimizeStopSequenceAction:

  Manually performed ChangeToursActions can lead to suboptimal trip structures (concerning the overall tour travel and driving time). So especially at the end of the process of manipulating tours by hand it can be useful to execute an OptimizeStopSequenceAction to improve the stop sequence of trips.

Tour Violations

The PTV xTour service itself only plans valid tours that respect all restrictions. In practice, not all the restrictions are really that strict, for example a user might approve a truck with an overload of 500 grams.

With a ChangeToursRequest it is possible to create violated tours. The violations will be reported in the ToursResponse in an overview as vehicleIdsWithTourViolations or more detailed in the different ViolationReports and as tourViolations in the TourEvents.

For an overview of all possible tour violations please have a look at the diagram TourViolation.

Good to know

Related Topics